home *** CD-ROM | disk | FTP | other *** search
/ Aminet 22 / Aminet 22 (1997)(GTI - Schatztruhe)[!][Dec 1997].iso / Aminet / dev / c / remote.lha / remote / doc / Manual
Text File  |  1997-10-09  |  10KB  |  217 lines
  1. AUTHOR
  2.  
  3.     Dietmar Eilert
  4.     Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  5.     WWW: http://www.clearlight.com/~dietmar
  6.     E-Mail: dietmar@tomate.tng.oche.de
  7.             Dietmar.Eilert@post.rwth-aachen.de
  8.     Tel: +49-(0)241-81665
  9.          +49-(0)2525-7776
  10.     Fax: +49-(0)241-81665
  11.  
  12. COPYRIGHT
  13.  
  14.     All  executables  and  the  library  in  this  package   (remote.library,
  15.     remoteopen,  remoteconfig) are freely distributable public domain softare
  16.     and may be included with other software. All other  files  (source  code,
  17.     install  script,  documentation,  etc.) are copyrighted by the author and
  18.     may not be included with other software.
  19.  
  20. INSTALLATION
  21.  
  22.     Doubleclick at the installer script icon.
  23.  
  24. DESCRIPTION
  25.  
  26.     RA is a shared library to open  files  in  remote  applications  (e.g.  a
  27.     browser)  without  knowledge of the executable name, its location on disk
  28.     or its ARexx  port.  Example  usage:  add  a  go-online  button  to  your
  29.     application  and  use  this  library  to run the browser and to show your
  30.     homepage. With less than five lines of code.
  31.  
  32.     The  package  includes  freely  distributable  library  frontends  (shell
  33.     commands)  for  use  in  installer  scripts  so that software authors can
  34.     directly register their programs as default application  for  appropriate
  35.     application classes.
  36.  
  37. EXAMPLE
  38.  
  39.     This example demonstrates how simple usage of this libary is -  it  opens
  40.     the specified url (STRPTR) in a web browser:
  41.  
  42.     if (RemoteBase = OpenLibrary("remote.library", 37)) {
  43.  
  44.         int error = RemoteOpen("BROWSER", NULL, url, REMOTE_OPEN_ASYNC);
  45.  
  46.         CloseLibrary(RemoteBase);
  47.     }
  48.  
  49.     RA uses a database of application descriptions  to  find  information  on
  50.     applications  stored  on the user's computer. A small default database is
  51.     shipped with this  package.  It  includes  preconfigured  information  on
  52.     common  Amiga  applications. New application descriptions can be added to
  53.     the database with the remoteconfig program (the idea behind  remoteconfig
  54.     is  that  future installation scripts will directly register applications
  55.     with  RA).  The  library  will  use  the  database  to  find  the  listed
  56.     applications  on  the  user's  computer.  This process is called database
  57.     validation. It involves scanning all local drives.  Once  validated,  all
  58.     applications  detected  during  validation  can  be  accessed through the
  59.     library functions on a class basis: programmers won't deal with  specific
  60.     applications  but  with  application  classes like BROWSER or EDITOR. The
  61.     library  will  then  resolve  your  requests  and  internally  select  an
  62.     application (with preference given to running applications).
  63.  
  64. THE USER FILES
  65.  
  66.     RA includes two command files for shell usage and for usage in  installer
  67.     scripts  (you  are  encouraged  to  ship these files with your software):
  68.     remoteconfig and remoteopen. Place these files in your "c:" folder if you
  69.     plan to use them often.
  70.  
  71.     1. bin/remoteopen
  72.  
  73.     remoteopen is used to run registered applications and to  open  files  in
  74.     registered  applications.  The  command  template (syntax) is: remoteopen
  75.     CLASS/A,FILE/K,APP/K. CLASS/A is the application  class.  FILE/K  is  the
  76.     file  you  would  like  to  open. And APP/K is the name of your preferred
  77.     application for this job (if you  have  any  preference).  The  following
  78.     example will open an URL in the web browser:
  79.  
  80.          remoteopen BROWSER file="http://www.clearlight.com/~dietmar".
  81.  
  82.     2. bin/remoteconfig
  83.  
  84.     remoteconfig is used to validate and to  configure  the  RA  database  of
  85.     applications.   The   command   template   (syntax)  of  remoteconfig  is
  86.     remoteconfig  ADD/K,DEL/K,VALIDATE/S,FOLDER/K,DEEP/S.  ADD/K   adds   the
  87.     specified  configuration string to the database. The configuration string
  88.     must end with an LF code (further format details can be found below;  see
  89.     "database  format").  DEL/K deletes the specified application(s) from the
  90.     database. You may use wildcards to delete multiple applications. Finally,
  91.     VALIDATE/S  starts  the  database  validation process, ie. a disk scan to
  92.     locate applications on your drives. DEEP/S and FOLDER/K may  be  used  to
  93.     refine  the  validation  process:  RA  defaults  to use a smart searching
  94.     strategy to keep the time required for a disk scan as  low  as  possible.
  95.     However,  RA  may  fail  to detect all applications in smart mode. DEEP/S
  96.     will force RA to use slow conventional searching  instead.  The  FOLDER/K
  97.     parameter  can  be  used  to set the starting point for the drive scan to
  98.     further minimize validation time (why waste time on searching all  drives
  99.     if you install your software in "software:" ?). Examples:
  100.  
  101.         remoteconfig validate
  102.  
  103.         remoteconfig validate folder="c:"
  104.  
  105.         remoteconfig add="class=BROWSER name=AWeb exe=aweb *n"
  106.  
  107.         remoteconfig del="#?aweb#?"
  108.  
  109. THE LIBRARY
  110.  
  111.     A description of the  library  interface  for  programmers  who  wish  to
  112.     interface  to  the library directly without using remoteopen/remoteconfig
  113.     can be found in the autodoc file  "developer/library/autodoc/remote.doc".
  114.     The following library functions are available:
  115.  
  116.         remote.library/RemoteInit
  117.         remote.library/RemoteAdd
  118.         remote.library/RemoteRemove
  119.         remote.library/RemoteOpen
  120.         remote.library/RemoteValidate
  121.  
  122. DATABASE FORMAT
  123.  
  124.     The database usually is kept in the file "s:remote.ini" (or optionally in
  125.     the file the environment variable "remote.cfg" is pointing to). It can be
  126.     viewed and modified with any text editor. The  average  user  will  never
  127.     have  to deal with this file while software authors should understand the
  128.     database format so that they can register their own applications  in  the
  129.     database (the remoteconfig command uses the same format). This is how the
  130.     database file might look like on your computer:
  131.  
  132.     ; remote.library configuration file (wildcards supported in VERSION/K,PORT/K,INSTALLPATH/K)
  133.     CLASS="BROWSER" NAME="IBrowse" VERSION="" INSTALLPATH="#?/ibrowse/" EXE="ibrowse" MINSIZE=100000 STACK=8192 ASSIGN="" PORT="IBROWSE" OPEN="*"%s*"" OPENRX="GOTOURL *"%s*""
  134.     CLASS="BROWSER" NAME="AWeb DEMO" VERSION="#?DEMO#?" INSTALLPATH="#?/aweb#?" EXE="aweb" MINSIZE=100000 STACK=16384 ASSIGN="AWEB:" PORT="" OPEN="*"%s*"" OPENRX=""
  135.     CLASS="BROWSER" NAME="AWeb" VERSION="~(#?DEMO#?)" INSTALLPATH="#?/aweb#?" EXE="aweb" MINSIZE=100000 STACK=16384 ASSIGN="AWEB:" PORT="AWEB.#?" OPEN="*"%s*"" OPENRX="OPEN *"%s*""
  136.     CLASS="BROWSER" NAME="Mindwalker" VERSION="" INSTALLPATH="" EXE="mindwaker" MINSIZE=100000 STACK=32768 ASSIGN="" PORT="MINDWALKER" OPEN="*"%s*"" OPENRX="OPENURL *"%s*""
  137.     CLASS="BROWSER" NAME="Voyager NG" VERSION="" INSTALLPATH="#?/voyager/" EXE="v" MINSIZE=100000 STACK=65536 ASSIGN="" PORT="VOYAGER" OPEN="*"%s*"" OPENRX="OPENURL *"%s*""
  138.  
  139.     There is exactly one entry (line) for  each  application.  It  lists  the
  140.     application  class,  the  application  name and a few other details which
  141.     will be used by the library to locate and access the applications.  Order
  142.     in  this  file  is  important: RA will scan the database file from top to
  143.     bottom when looking for applications. The syntax you  use  in  this  file
  144.     will  have  to conform with AmigaDOS rules. For example, string arguments
  145.     must be given in quotation marks if they contain spaces. Quotation  marks
  146.     in  strings can be inserted as *". Linefeeds can be inserted as *n. Below
  147.     is a description of all options:
  148.  
  149. CLASS
  150.  
  151.     The application class. While you can freely choose any string you like  I
  152.     would suggest that you only use class names from the list below (and that
  153.     you register new names with the RA author to have them included here).
  154.  
  155.         EDITOR         Editor for ASCII files
  156.         WORDPROCESSOR  Editor for RTF
  157.         HTMLEDITOR     Editor for HTML
  158.         MAILTO         E-Mail sender
  159.         PLAYWAV        Player for WAV
  160.         TCPSTACK       TCP stack
  161.         VIEWGUIDE      Viewer for guides
  162.         VIEWIMAGE      Viewer for images
  163.         SPOOLER        Spooler for ASCII files
  164.         BROWSER        WWW browser
  165.  
  166. NAME
  167.  
  168.     A symbolic application name; can be chosen freely.
  169.  
  170. VERSION
  171.  
  172.     Version requirement: This pattern is  pattern-matched  with  the  version
  173.     string  found  in files during database validation to improve reliability
  174.     of executable identification
  175.  
  176. INSTALLPATH
  177.  
  178.     Path requirement (root directory): This pattern is  pattern-matched  with
  179.     the  path  to  files during database validation to improve reliability of
  180.     executable identification.
  181.  
  182. EXE
  183.  
  184.     The executable name.
  185.  
  186. MINSIZE
  187.  
  188.     The executable size given here is  used  during  database  validation  to
  189.     improve  validation  reliability: files smaller than MINSIZE are ignored.
  190.     Consider that compression may be used on some systems: the MINSIZE  value
  191.     should  not  exceed  50%  of  the  real  file  size  so  that  compressed
  192.     executables can still be identified.
  193.  
  194. STACK
  195.  
  196.     The minimum stack required to run the program.
  197.  
  198. ASSIGN
  199.  
  200.     Some applications require that a new assign  to  the  root  directory  is
  201.     created  during  installation. You can specify the assign in the database
  202.     to help RA improve reliability of executable identification.
  203.  
  204. PORT
  205.  
  206.     ARexx port name of the application (may contain wildcards).
  207.  
  208. OPEN
  209.  
  210.     The argument template for passing a file name to the application when  it
  211.     is started (if RA can't find running applications).
  212.  
  213. OPENRX
  214.  
  215.     The argument template for passing a file name to the application's  ARexx
  216.     port (if RA can find running applications).
  217.